XML and the art of code maintenance

We present three distinct XML vocabularies and demonstrate integration with o:XML source code. The vocabularies relate to interface documentation, unit tests and Design By Contract conditions. By layering the information with XML namespaces, syntax conflicts are avoided and selective processing can be performed using standard XML tools. Automated unit tests and the implementation of Design By Contract using code transformations is explained in detail. There is also a discussion on the use of extension elements to customize the development process, using Extreme Programming and Design By Contract as examples. Embedding Documentation Practically all programming languages provide support for embedding documentation with the source code in the form of comments. Some support a standard syntax for documenting application interfaces, and have tools that automatically generate documentation. In the case of Java, this has resulted in vast improvements in the overall situation of API documentation. One problem is that in order to harvest the documentation, you need to parse and understand the source code. In o:XML, the core language does not provide a documentation or commenting mechanism. Instead, this is accomplished by adding in a documentation vocabulary, a new syntax superimposed on the code syntax. Clean separation from the actual code is achieved by using separate XML namespaces. The advantage of using extensions this way is that they can be as simple or as sophisticated as is deemed necessary. Since there is no conflict with the source code, there are no real limitations to how the vocabulary is constructed. Furthermore existing XML vocabularies can be effectively reused. In the case of adding documentation to our source code, it would be quite easy to incorporate an existing format such as DocBook [http://www.docbook.org]. The vocabulary we use for o:XML is based on the specific requirements of documenting code it covers function and procedure parameters, return values, exceptions and similar information, and it takes full advantage of the code context. Example 2.1. Embedding Documentation: Node.insertBefore(Node) Node is the base type of all other types. Insert another node before this one in the parents set of child nodes. The node to insert. The current node. ...